<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
  <head>
    <title>
Bugzilla::DB</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  <link rel="stylesheet" title="style" type="text/css" href=".././../../../style.css" media="all" >

</head>
  <body id="pod">
<p class="backlinktop"><b><a name="___top" href="../index.html" accesskey="1" title="All Documents">&lt;&lt;</a></b></p>
<h1>Bugzilla::DB</h1>
<div class='indexgroup'>
<ul   class='indexList indexList1'>
  <li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
  <li class='indexItem indexItem1'><a href='#SYNOPSIS'>SYNOPSIS</a>
  <li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
  <li class='indexItem indexItem1'><a href='#CONSTANTS'>CONSTANTS</a>
  <li class='indexItem indexItem1'><a href='#CONNECTION'>CONNECTION</a>
  <ul   class='indexList indexList2'>
    <li class='indexItem indexItem2'><a href='#Functions'>Functions</a>
  </ul>
  <li class='indexItem indexItem1'><a href='#ABSTRACT_METHODS'>ABSTRACT METHODS</a>
  <ul   class='indexList indexList2'>
    <li class='indexItem indexItem2'><a href='#Constructor'>Constructor</a>
    <li class='indexItem indexItem2'><a href='#SQL_Generation'>SQL Generation</a>
  </ul>
  <li class='indexItem indexItem1'><a href='#IMPLEMENTED_METHODS'>IMPLEMENTED METHODS</a>
  <ul   class='indexList indexList2'>
    <li class='indexItem indexItem2'><a href='#General_Information_Methods'>General Information Methods</a>
    <li class='indexItem indexItem2'><a href='#Database_Setup_Methods'>Database Setup Methods</a>
    <li class='indexItem indexItem2'><a href='#Schema_Modification_Methods'>Schema Modification Methods</a>
    <li class='indexItem indexItem2'><a href='#Schema_Information_Methods'>Schema Information Methods</a>
    <li class='indexItem indexItem2'><a href='#Transaction_Methods'>Transaction Methods</a>
  </ul>
  <li class='indexItem indexItem1'><a href='#SUBCLASS_HELPERS'>SUBCLASS HELPERS</a>
  <li class='indexItem indexItem1'><a href='#SEE_ALSO'>SEE ALSO</a>
</ul>
</div>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="NAME"
>NAME</a></h1>

<p>Bugzilla::DB - Database access routines,
using <a href="../DBI.html" class="podlinkpod"
>DBI</a></p>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="SYNOPSIS"
>SYNOPSIS</a></h1>

<pre  class="code">  # Obtain db handle
  use Bugzilla::DB;
  my $dbh = Bugzilla-&#62;dbh;

  # prepare a query using DB methods
  my $sth = $dbh-&#62;prepare(&#34;SELECT &#34; .
                          $dbh-&#62;sql_date_format(&#34;creation_ts&#34;, &#34;%Y%m%d&#34;) .
                          &#34; FROM bugs WHERE bug_status != &#39;RESOLVED&#39; &#34; .
                          $dbh-&#62;sql_limit(1));

  # Execute the query
  $sth-&#62;execute;

  # Get the results
  my @result = $sth-&#62;fetchrow_array;

  # Schema Modification
  $dbh-&#62;bz_add_column($table, $name, \%definition, $init_value);
  $dbh-&#62;bz_add_index($table, $name, $definition);
  $dbh-&#62;bz_add_table($name);
  $dbh-&#62;bz_drop_index($table, $name);
  $dbh-&#62;bz_drop_table($name);
  $dbh-&#62;bz_alter_column($table, $name, \%new_def, $set_nulls_to);
  $dbh-&#62;bz_drop_column($table, $column);
  $dbh-&#62;bz_rename_column($table, $old_name, $new_name);

  # Schema Information
  my $column = $dbh-&#62;bz_column_info($table, $column);
  my $index  = $dbh-&#62;bz_index_info($table, $index);</pre>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="DESCRIPTION"
>DESCRIPTION</a></h1>

<p>Functions in this module allows creation of a database handle to connect to the Bugzilla database. This should never be done directly; all users should use the <a href="../Bugzilla.html" class="podlinkpod"
>Bugzilla</a> module to access the current <code  class="code">dbh</code> instead.</p>

<p>This module also contains methods extending the returned handle with functionality which is different between databases allowing for easy customization for particular database via inheritance. These methods should be always preffered over hard-coding SQL commands.</p>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="CONSTANTS"
>CONSTANTS</a></h1>

<p>Subclasses of Bugzilla::DB are required to define certain constants. These constants are required to be subroutines or &#34;use constant&#34; variables.</p>

<dl>
<dt><a name="BLOB_TYPE"
><code  class="code">BLOB_TYPE</code></a></dt>

<dd>
<p>The <code  class="code">\%attr</code> argument that must be passed to bind_param in order to correctly escape a <code  class="code">LONGBLOB</code> type.</p>

<dt><a name="ISOLATION_LEVEL"
><code  class="code">ISOLATION_LEVEL</code></a></dt>

<dd>
<p>The argument that this database should send to <code  class="code">SET TRANSACTION ISOLATION LEVEL</code> when starting a transaction. If you override this in a subclass, the isolation level you choose should be as strict as or more strict than the default isolation level defined in <a href="../Bugzilla/DB.html" class="podlinkpod"
>Bugzilla::DB</a>.</p>
</dd>
</dl>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="CONNECTION"
>CONNECTION</a></h1>

<p>A new database handle to the required database can be created using this module. This is normally done by the <a href="../Bugzilla.html" class="podlinkpod"
>Bugzilla</a> module, and so these routines should not be called from anywhere else.</p>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="Functions"
>Functions</a></h2>

<dl>
<dt><a name="connect_main"
><code  class="code">connect_main</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Function to connect to the main database, returning a new database handle.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a 
><code  class="code">$no_db_name</code> (optional) - If true, connect to the database server, but don&#39;t connect to a specific database. This is only used when creating a database. After you create the database, you should re-create a new Bugzilla::DB object without using this parameter.</a></dt>
</dl>

<dt><a name="Returns"
><b>Returns</b></a></dt>

<dd>
<p>New instance of the DB class</p>
</dd>
</dl>

<dt><a name="connect_shadow"
><code  class="code">connect_shadow</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Function to connect to the shadow database, returning a new database handle. This routine <code  class="code">die</code>s if no shadow database is configured.</p>

<dt><a name="Params_(none)"
><b>Params</b> (none)</a></dt>

<dd>
<dt><a name="Returns"
><b>Returns</b></a></dt>

<dd>
<p>A new instance of the DB class</p>
</dd>
</dl>

<dt><a name="bz_check_requirements"
><code  class="code">bz_check_requirements</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Checks to make sure that you have the correct DBD and database version installed for the database that Bugzilla will be using. Prints a message and exits if you don&#39;t pass the requirements.</p>

<p>If <code  class="code">$db_check</code> is false (from <em  class="code">localconfig</em>), we won&#39;t check the database version.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$output_-_true_if_the_function_should_display_informational_output_about_what_it&#39;s_doing,_such_as_versions_found."
><code  class="code">$output</code> - <code  class="code">true</code> if the function should display informational output about what it&#39;s doing, such as versions found.</a></dt>
</dl>

<dt><a name="Returns_(nothing)"
><b>Returns</b> (nothing)</a></dt>
</dl>

<dt><a name="bz_create_database"
><code  class="code">bz_create_database</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Creates an empty database with the name <code  class="code">$db_name</code>, if that database doesn&#39;t already exist. Prints an error message and exits if we can&#39;t create the database.</p>

<dt><a name="Params_(none)"
><b>Params</b> (none)</a></dt>

<dd>
<dt><a name="Returns_(nothing)"
><b>Returns</b> (nothing)</a></dt>
</dl>

<dt><a name="_connect"
><code  class="code">_connect</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Internal function, creates and returns a new, connected instance of the correct DB class. This routine <code  class="code">die</code>s if no driver is specified.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$driver_-_name_of_the_database_driver_to_use"
><code  class="code">$driver</code> - name of the database driver to use</a></dt>

<dd>
<dt><a name="$host_-_host_running_the_database_we_are_connecting_to"
><code  class="code">$host</code> - host running the database we are connecting to</a></dt>

<dd>
<dt><a name="$dbname_-_name_of_the_database_to_connect_to"
><code  class="code">$dbname</code> - name of the database to connect to</a></dt>

<dd>
<dt><a name="$port_-_port_the_database_is_listening_on"
><code  class="code">$port</code> - port the database is listening on</a></dt>

<dd>
<dt><a name="$sock_-_socket_the_database_is_listening_on"
><code  class="code">$sock</code> - socket the database is listening on</a></dt>

<dd>
<dt><a name="$user_-_username_used_to_log_in_to_the_database"
><code  class="code">$user</code> - username used to log in to the database</a></dt>

<dd>
<dt><a name="$pass_-_password_used_to_log_in_to_the_database"
><code  class="code">$pass</code> - password used to log in to the database</a></dt>
</dl>

<dt><a name="Returns"
><b>Returns</b></a></dt>

<dd>
<p>A new instance of the DB class</p>
</dd>
</dl>

<dt><a name="_handle_error"
><code  class="code">_handle_error</code></a></dt>

<dd>
<p>Function passed to the DBI::connect call for error handling. It shortens the error for printing.</p>

<dt><a name="import"
><code  class="code">import</code></a></dt>

<dd>
<p>Overrides the standard import method to check that derived class implements all required abstract methods. Also calls original implementation in its super class.</p>
</dd>
</dl>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="ABSTRACT_METHODS"
>ABSTRACT METHODS</a></h1>

<p>Note: Methods which can be implemented generically for all DBs are implemented in this module. If needed, they can be overridden with DB specific code. Methods which do not have standard implementation are abstract and must be implemented for all supported databases separately. To avoid confusion with standard DBI methods, all methods returning string with formatted SQL command have prefix <code  class="code">sql_</code>. All other methods have prefix <code  class="code">bz_</code>.</p>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="Constructor"
>Constructor</a></h2>

<dl>
<dt><a name="new"
><code  class="code">new</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Constructor. Abstract method, should be overridden by database specific code.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$user_-_username_used_to_log_in_to_the_database"
><code  class="code">$user</code> - username used to log in to the database</a></dt>

<dd>
<dt><a name="$pass_-_password_used_to_log_in_to_the_database"
><code  class="code">$pass</code> - password used to log in to the database</a></dt>

<dd>
<dt><a name="$host_-_host_running_the_database_we_are_connecting_to"
><code  class="code">$host</code> - host running the database we are connecting to</a></dt>

<dd>
<dt><a name="$dbname_-_name_of_the_database_to_connect_to"
><code  class="code">$dbname</code> - name of the database to connect to</a></dt>

<dd>
<dt><a name="$port_-_port_the_database_is_listening_on"
><code  class="code">$port</code> - port the database is listening on</a></dt>

<dd>
<dt><a name="$sock_-_socket_the_database_is_listening_on"
><code  class="code">$sock</code> - socket the database is listening on</a></dt>
</dl>

<dt><a name="Returns"
><b>Returns</b></a></dt>

<dd>
<p>A new instance of the DB class</p>

<dt><a name="Note"
><b>Note</b></a></dt>

<dd>
<p>The constructor should create a DSN from the parameters provided and then call <code  class="code">db_new()</code> method of its super class to create a new class instance. See <a href="../db_new.html" class="podlinkpod"
>db_new</a> description in this module. As per DBI documentation, all class variables must be prefixed with &#34;private_&#34;. See <a href="../DBI.html" class="podlinkpod"
>DBI</a>.</p>
</dd>
</dl>
</dd>
</dl>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="SQL_Generation"
>SQL Generation</a></h2>

<dl>
<dt><a name="sql_regexp"
><code  class="code">sql_regexp</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Outputs SQL regular expression operator for POSIX regex searches (case insensitive) in format suitable for a given database.</p>

<p>Abstract method, should be overridden by database specific code.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$expr_-_SQL_expression_for_the_text_to_be_searched_(scalar)"
><code  class="code">$expr</code> - SQL expression for the text to be searched (scalar)</a></dt>

<dd>
<dt><a name="$pattern_-_the_regular_expression_to_search_for_(scalar)"
><code  class="code">$pattern</code> - the regular expression to search for (scalar)</a></dt>

<dd>
<dt><a name="$nocheck_-_true_if_the_pattern_should_not_be_tested;_false_otherwise_(boolean)"
><code  class="code">$nocheck</code> - true if the pattern should not be tested; false otherwise (boolean)</a></dt>

<dd>
<dt><a name="$real_pattern_-_the_real_regular_expression_to_search_for._This_argument_is_used_when_$pattern_is_a_placeholder_(&#39;?&#39;)."
><code  class="code">$real_pattern</code> - the real regular expression to search for. This argument is used when <code  class="code">$pattern</code> is a placeholder (&#39;?&#39;).</a></dt>
</dl>

<dt><a name="Returns"
><b>Returns</b></a></dt>

<dd>
<p>Formatted SQL for regular expression search (e.g. REGEXP) (scalar)</p>
</dd>
</dl>

<dt><a name="sql_not_regexp"
><code  class="code">sql_not_regexp</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Outputs SQL regular expression operator for negative POSIX regex searches (case insensitive) in format suitable for a given database.</p>

<p>Abstract method, should be overridden by database specific code.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<p>Same as <a href="#sql_regexp" class="podlinkpod"
>&#34;sql_regexp&#34;</a>.</p>

<dt><a name="Returns"
><b>Returns</b></a></dt>

<dd>
<p>Formatted SQL for negative regular expression search (e.g. NOT REGEXP) (scalar)</p>
</dd>
</dl>

<dt><a name="sql_limit"
><code  class="code">sql_limit</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Returns SQL syntax for limiting results to some number of rows with optional offset if not starting from the begining.</p>

<p>Abstract method, should be overridden by database specific code.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$limit_-_number_of_rows_to_return_from_query_(scalar)"
><code  class="code">$limit</code> - number of rows to return from query (scalar)</a></dt>

<dd>
<dt><a name="$offset_-_number_of_rows_to_skip_before_counting_(scalar)"
><code  class="code">$offset</code> - number of rows to skip before counting (scalar)</a></dt>
</dl>

<dt><a name="Returns"
><b>Returns</b></a></dt>

<dd>
<p>Formatted SQL for limiting number of rows returned from query with optional offset (e.g. LIMIT 1, 1) (scalar)</p>
</dd>
</dl>

<dt><a name="sql_from_days"
><code  class="code">sql_from_days</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Outputs SQL syntax for converting Julian days to date.</p>

<p>Abstract method, should be overridden by database specific code.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$days_-_days_to_convert_to_date"
><code  class="code">$days</code> - days to convert to date</a></dt>
</dl>

<dt><a name="Returns"
><b>Returns</b></a></dt>

<dd>
<p>Formatted SQL for returning Julian days in dates. (scalar)</p>
</dd>
</dl>

<dt><a name="sql_to_days"
><code  class="code">sql_to_days</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Outputs SQL syntax for converting date to Julian days.</p>

<p>Abstract method, should be overridden by database specific code.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$date_-_date_to_convert_to_days"
><code  class="code">$date</code> - date to convert to days</a></dt>
</dl>

<dt><a name="Returns"
><b>Returns</b></a></dt>

<dd>
<p>Formatted SQL for returning date fields in Julian days. (scalar)</p>
</dd>
</dl>

<dt><a name="sql_date_format"
><code  class="code">sql_date_format</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Outputs SQL syntax for formatting dates.</p>

<p>Abstract method, should be overridden by database specific code.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$date_-_date_or_name_of_date_type_column_(scalar)"
><code  class="code">$date</code> - date or name of date type column (scalar)</a></dt>

<dd>
<dt><a 
><code  class="code">$format</code> - format string for date output (scalar) (<code  class="code">%Y</code> = year, four digits, <code  class="code">%y</code> = year, two digits, <code  class="code">%m</code> = month, <code  class="code">%d</code> = day, <code  class="code">%a</code> = weekday name, 3 letters, <code  class="code">%H</code> = hour 00-23, <code  class="code">%i</code> = minute, <code  class="code">%s</code> = second)</a></dt>
</dl>

<dt><a name="Returns"
><b>Returns</b></a></dt>

<dd>
<p>Formatted SQL for date formatting (scalar)</p>
</dd>
</dl>

<dt><a name="sql_interval"
><code  class="code">sql_interval</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Outputs proper SQL syntax for a time interval function.</p>

<p>Abstract method, should be overridden by database specific code.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$interval_-_the_time_interval_requested_(e.g._&#39;30&#39;)_(integer)"
><code  class="code">$interval</code> - the time interval requested (e.g. &#39;30&#39;) (integer)</a></dt>

<dd>
<dt><a name="$units_-_the_units_the_interval_is_in_(e.g._&#39;MINUTE&#39;)_(string)"
><code  class="code">$units</code> - the units the interval is in (e.g. &#39;MINUTE&#39;) (string)</a></dt>
</dl>

<dt><a name="Returns"
><b>Returns</b></a></dt>

<dd>
<p>Formatted SQL for interval function (scalar)</p>
</dd>
</dl>

<dt><a name="sql_position"
><code  class="code">sql_position</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Outputs proper SQL syntax determining position of a substring (fragment) withing a string (text). Note: if the substring or text are string constants, they must be properly quoted (e.g. &#34;&#39;pattern&#39;&#34;).</p>

<p>It searches for the string in a case-sensitive manner. If you want to do a case-insensitive search, use <a href="#sql_iposition" class="podlinkpod"
>&#34;sql_iposition&#34;</a>.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$fragment_-_the_string_fragment_we_are_searching_for_(scalar)"
><code  class="code">$fragment</code> - the string fragment we are searching for (scalar)</a></dt>

<dd>
<dt><a name="$text_-_the_text_to_search_(scalar)"
><code  class="code">$text</code> - the text to search (scalar)</a></dt>
</dl>

<dt><a name="Returns"
><b>Returns</b></a></dt>

<dd>
<p>Formatted SQL for substring search (scalar)</p>
</dd>
</dl>

<dt><a name="sql_iposition"
><code  class="code">sql_iposition</code></a></dt>

<dd>
<p>Just like <a href="#sql_position" class="podlinkpod"
>&#34;sql_position&#34;</a>, but case-insensitive.</p>

<dt><a name="sql_group_by"
><code  class="code">sql_group_by</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Outputs proper SQL syntax for grouping the result of a query.</p>

<p>For ANSI SQL databases, we need to group by all columns we are querying for (except for columns used in aggregate functions). Some databases require (or even allow) to specify only one or few columns if the result is uniquely defined. For those databases, the default implementation needs to be overloaded.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$needed_columns_-_string_with_comma_separated_list_of_columns_we_need_to_group_by_to_get_expected_result_(scalar)"
><code  class="code">$needed_columns</code> - string with comma separated list of columns we need to group by to get expected result (scalar)</a></dt>

<dd>
<dt><a 
><code  class="code">$optional_columns</code> - string with comma separated list of all other columns we are querying for, but which are not in the required list.</a></dt>
</dl>

<dt><a name="Returns"
><b>Returns</b></a></dt>

<dd>
<p>Formatted SQL for row grouping (scalar)</p>
</dd>
</dl>

<dt><a name="sql_string_concat"
><code  class="code">sql_string_concat</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Returns SQL syntax for concatenating multiple strings (constants or values from table columns) together.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="@params_-_array_of_column_names_or_strings_to_concatenate"
><code  class="code">@params</code> - array of column names or strings to concatenate</a></dt>
</dl>

<dt><a name="Returns"
><b>Returns</b></a></dt>

<dd>
<p>Formatted SQL for concatenating specified strings</p>
</dd>
</dl>

<dt><a name="sql_string_until"
><code  class="code">sql_string_until</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Returns SQL for truncating a string at the first occurrence of a certain substring.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<p>Note that both parameters need to be sql-quoted.</p>

<dt><a name="$string_The_string_we&#39;re_truncating"
><code  class="code">$string</code> The string we&#39;re truncating</a></dt>

<dd>
<dt><a name="$substring_The_substring_we&#39;re_truncating_at."
><code  class="code">$substring</code> The substring we&#39;re truncating at.</a></dt>
</dl>

<dt><a name="sql_fulltext_search"
><code  class="code">sql_fulltext_search</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Returns SQL syntax for performing a full text search for specified text on a given column.</p>

<p>There is a ANSI SQL version of this method implemented using LIKE operator, but it&#39;s not a real full text search. DB specific modules should override this, as this generic implementation will be always much slower. This generic implementation returns &#39;relevance&#39; as 0 for no match, or 1 for a match.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$column_-_name_of_column_to_search_(scalar)"
><code  class="code">$column</code> - name of column to search (scalar)</a></dt>

<dd>
<dt><a name="$text_-_text_to_search_for_(scalar)"
><code  class="code">$text</code> - text to search for (scalar)</a></dt>
</dl>

<dt><a name="Returns"
><b>Returns</b></a></dt>

<dd>
<p>Formatted SQL for full text search</p>
</dd>
</dl>

<dt><a name="sql_istrcmp"
><code  class="code">sql_istrcmp</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Returns SQL for a case-insensitive string comparison.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$left_-_What_should_be_on_the_left-hand-side_of_the_operation."
><code  class="code">$left</code> - What should be on the left-hand-side of the operation.</a></dt>

<dd>
<dt><a name="$right_-_What_should_be_on_the_right-hand-side_of_the_operation."
><code  class="code">$right</code> - What should be on the right-hand-side of the operation.</a></dt>

<dd>
<dt><a 
><code  class="code">$op</code> (optional) - What the operation is. Should be a valid ANSI SQL comparison operator, such as <code  class="code">=</code>, <code  class="code">&#60;</code>, <code  class="code">LIKE</code>, etc. Defaults to <code  class="code">=</code> if not specified.</a></dt>
</dl>

<dt><a name="Returns"
><b>Returns</b></a></dt>

<dd>
<p>A SQL statement that will run the comparison in a case-insensitive fashion.</p>

<dt><a name="Note"
><b>Note</b></a></dt>

<dd>
<p>Uses <a href="#sql_istring" class="podlinkpod"
>&#34;sql_istring&#34;</a>, so it has the same performance concerns. Try to avoid using this function unless absolutely necessary.</p>

<p>Subclass Implementors: Override sql_istring instead of this function, most of the time (this function uses sql_istring).</p>
</dd>
</dl>

<dt><a name="sql_istring"
><code  class="code">sql_istring</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Returns SQL syntax &#34;preparing&#34; a string or text column for case-insensitive comparison.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$string_-_string_to_convert_(scalar)"
><code  class="code">$string</code> - string to convert (scalar)</a></dt>
</dl>

<dt><a name="Returns"
><b>Returns</b></a></dt>

<dd>
<p>Formatted SQL making the string case insensitive.</p>

<dt><a name="Note"
><b>Note</b></a></dt>

<dd>
<p>The default implementation simply calls LOWER on the parameter. If this is used to search on a text column with index, the index will not be usually used unless it was created as LOWER(column).</p>
</dd>
</dl>

<dt><a name="sql_in"
><code  class="code">sql_in</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Returns SQL syntax for the <code  class="code">IN ()</code> operator.</p>

<p>Only necessary where an <code  class="code">IN</code> clause can have more than 1000 items.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$column_name_-_Column_name_(e.g._bug_id)"
><code  class="code">$column_name</code> - Column name (e.g. <code  class="code">bug_id</code>)</a></dt>

<dd>
<dt><a name="$in_list_ref_-_an_arrayref_containing_values_for_IN_()"
><code  class="code">$in_list_ref</code> - an arrayref containing values for <code  class="code">IN ()</code></a></dt>
</dl>

<dt><a name="Returns"
><b>Returns</b></a></dt>

<dd>
<p>Formatted SQL for the <code  class="code">IN</code> operator.</p>
</dd>
</dl>
</dd>
</dl>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="IMPLEMENTED_METHODS"
>IMPLEMENTED METHODS</a></h1>

<p>These methods are implemented in Bugzilla::DB, and only need to be implemented in subclasses if you need to override them for database-compatibility reasons.</p>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="General_Information_Methods"
>General Information Methods</a></h2>

<p>These methods return information about data in the database.</p>

<dl>
<dt><a name="bz_last_key"
><code  class="code">bz_last_key</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Returns the last serial number, usually from a previous INSERT.</p>

<p>Must be executed directly following the relevant INSERT. This base implementation uses <a href="../DBI.html#last_insert_id" class="podlinkpod"
>&#34;last_insert_id&#34; in DBI</a>. If the DBD supports it, it is the preffered way to obtain the last serial index. If it is not supported, the DB-specific code needs to override this function.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$table_-_name_of_table_containing_serial_column_(scalar)"
><code  class="code">$table</code> - name of table containing serial column (scalar)</a></dt>

<dd>
<dt><a name="$column_-_name_of_column_containing_serial_data_type_(scalar)"
><code  class="code">$column</code> - name of column containing serial data type (scalar)</a></dt>
</dl>

<dt><a name="Returns"
><b>Returns</b></a></dt>

<dd>
<p>Last inserted ID (scalar)</p>
</dd>
</dl>
</dd>
</dl>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="Database_Setup_Methods"
>Database Setup Methods</a></h2>

<p>These methods are used by the Bugzilla installation programs to set up the database.</p>

<dl>
<dt><a name="bz_populate_enum_tables"
><code  class="code">bz_populate_enum_tables</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>For an upgrade or an initial installation, populates the tables that hold the legal values for the old &#34;enum&#34; fields: <code  class="code">bug_severity</code>, <code  class="code">resolution</code>, etc. Prints out information if it inserts anything into the DB.</p>

<dt><a name="Params_(none)"
><b>Params</b> (none)</a></dt>

<dd>
<dt><a name="Returns_(nothing)"
><b>Returns</b> (nothing)</a></dt>
</dl>
</dd>
</dl>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="Schema_Modification_Methods"
>Schema Modification Methods</a></h2>

<p>These methods modify the current Bugzilla Schema.</p>

<p>Where a parameter says &#34;Abstract index/column definition&#34;, it returns/takes information in the formats defined for indexes and columns in <code  class="code">Bugzilla::DB::Schema::ABSTRACT_SCHEMA</code>.</p>

<dl>
<dt><a name="bz_add_column"
><code  class="code">bz_add_column</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Adds a new column to a table in the database. Prints out a brief statement that it did so, to stdout. Note that you cannot add a NOT NULL column that has no default -- the database won&#39;t know what to set all the NULL values to.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$table_-_the_table_where_the_column_is_being_added"
><code  class="code">$table</code> - the table where the column is being added</a></dt>

<dd>
<dt><a name="$name_-_the_name_of_the_new_column"
><code  class="code">$name</code> - the name of the new column</a></dt>

<dd>
<dt><a name="\%definition_-_Abstract_column_definition_for_the_new_column"
><code  class="code">\%definition</code> - Abstract column definition for the new column</a></dt>

<dd>
<dt><a 
><code  class="code">$init_value</code> (optional) - An initial value to set the column to. Required if your column is NOT NULL and has no DEFAULT set.</a></dt>
</dl>

<dt><a name="Returns_(nothing)"
><b>Returns</b> (nothing)</a></dt>
</dl>

<dt><a name="bz_add_index"
><code  class="code">bz_add_index</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Adds a new index to a table in the database. Prints out a brief statement that it did so, to stdout. If the index already exists, we will do nothing.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$table_-_The_table_the_new_index_is_on."
><code  class="code">$table</code> - The table the new index is on.</a></dt>

<dd>
<dt><a name="$name_-_A_name_for_the_new_index."
><code  class="code">$name</code> - A name for the new index.</a></dt>

<dd>
<dt><a name="$definition_-_An_abstract_index_definition._Either_a_hashref_or_an_arrayref."
><code  class="code">$definition</code> - An abstract index definition. Either a hashref or an arrayref.</a></dt>
</dl>

<dt><a name="Returns_(nothing)"
><b>Returns</b> (nothing)</a></dt>
</dl>

<dt><a name="bz_add_table"
><code  class="code">bz_add_table</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Creates a new table in the database, based on the definition for that table in the abstract schema.</p>

<p>Note that unlike the other &#39;add&#39; functions, this does not take a definition, but always creates the table as it exists in <a href="../Bugzilla/DB/Schema.html#ABSTRACT_SCHEMA" class="podlinkpod"
>&#34;ABSTRACT_SCHEMA&#34; in Bugzilla::DB::Schema</a>.</p>

<p>If a table with that name already exists, then this function returns silently.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$name_-_The_name_of_the_table_you_want_to_create."
><code  class="code">$name</code> - The name of the table you want to create.</a></dt>
</dl>

<dt><a name="Returns_(nothing)"
><b>Returns</b> (nothing)</a></dt>
</dl>

<dt><a name="bz_drop_index"
><code  class="code">bz_drop_index</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Removes an index from the database. Prints out a brief statement that it did so, to stdout. If the index doesn&#39;t exist, we do nothing.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$table_-_The_table_that_the_index_is_on."
><code  class="code">$table</code> - The table that the index is on.</a></dt>

<dd>
<dt><a name="$name_-_The_name_of_the_index_that_you_want_to_drop."
><code  class="code">$name</code> - The name of the index that you want to drop.</a></dt>
</dl>

<dt><a name="Returns_(nothing)"
><b>Returns</b> (nothing)</a></dt>
</dl>

<dt><a name="bz_drop_table"
><code  class="code">bz_drop_table</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Drops a table from the database. If the table doesn&#39;t exist, we just return silently.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$name_-_The_name_of_the_table_to_drop."
><code  class="code">$name</code> - The name of the table to drop.</a></dt>
</dl>

<dt><a name="Returns_(nothing)"
><b>Returns</b> (nothing)</a></dt>
</dl>

<dt><a name="bz_alter_column"
><code  class="code">bz_alter_column</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Changes the data type of a column in a table. Prints out the changes being made to stdout. If the new type is the same as the old type, the function returns without changing anything.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$table_-_the_table_where_the_column_is"
><code  class="code">$table</code> - the table where the column is</a></dt>

<dd>
<dt><a name="$name_-_the_name_of_the_column_you_want_to_change"
><code  class="code">$name</code> - the name of the column you want to change</a></dt>

<dd>
<dt><a name="\%new_def_-_An_abstract_column_definition_for_the_new_data_type_of_the_columm"
><code  class="code">\%new_def</code> - An abstract column definition for the new data type of the columm</a></dt>

<dd>
<dt><a 
><code  class="code">$set_nulls_to</code> (Optional) - If you are changing the column to be NOT NULL, you probably also want to set any existing NULL columns to a particular value. Specify that value here. <b>NOTE</b>: The value should not already be SQL-quoted.</a></dt>
</dl>

<dt><a name="Returns_(nothing)"
><b>Returns</b> (nothing)</a></dt>
</dl>

<dt><a name="bz_drop_column"
><code  class="code">bz_drop_column</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Removes a column from a database table. If the column doesn&#39;t exist, we return without doing anything. If we do anything, we print a short message to <code  class="code">stdout</code> about the change.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$table_-_The_table_where_the_column_is"
><code  class="code">$table</code> - The table where the column is</a></dt>

<dd>
<dt><a name="$column_-_The_name_of_the_column_you_want_to_drop"
><code  class="code">$column</code> - The name of the column you want to drop</a></dt>
</dl>

<dt><a name="Returns_(nothing)"
><b>Returns</b> (nothing)</a></dt>
</dl>

<dt><a name="bz_rename_column"
><code  class="code">bz_rename_column</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Renames a column in a database table. If the <code  class="code">$old_name</code> column doesn&#39;t exist, we return without doing anything. If <code  class="code">$old_name</code> and <code  class="code">$new_name</code> both already exist in the table specified, we fail.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$table_-_The_name_of_the_table_containing_the_column_that_you_want_to_rename"
><code  class="code">$table</code> - The name of the table containing the column that you want to rename</a></dt>

<dd>
<dt><a name="$old_name_-_The_current_name_of_the_column_that_you_want_to_rename"
><code  class="code">$old_name</code> - The current name of the column that you want to rename</a></dt>

<dd>
<dt><a name="$new_name_-_The_new_name_of_the_column"
><code  class="code">$new_name</code> - The new name of the column</a></dt>
</dl>

<dt><a name="Returns_(nothing)"
><b>Returns</b> (nothing)</a></dt>
</dl>

<dt><a name="bz_rename_table"
><code  class="code">bz_rename_table</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Renames a table in the database. Does nothing if the table doesn&#39;t exist.</p>

<p>Throws an error if the old table exists and there is already a table with the new name.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$old_name_-_The_current_name_of_the_table."
><code  class="code">$old_name</code> - The current name of the table.</a></dt>

<dd>
<dt><a name="$new_name_-_What_you&#39;re_renaming_the_table_to."
><code  class="code">$new_name</code> - What you&#39;re renaming the table to.</a></dt>
</dl>

<dt><a name="Returns_(nothing)"
><b>Returns</b> (nothing)</a></dt>
</dl>
</dd>
</dl>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="Schema_Information_Methods"
>Schema Information Methods</a></h2>

<p>These methods return information about the current Bugzilla database schema, as it currently exists on the disk.</p>

<p>Where a parameter says &#34;Abstract index/column definition&#34;, it returns/takes information in the formats defined for indexes and columns for <a href="../Bugzilla/DB/Schema.html#ABSTRACT_SCHEMA" class="podlinkpod"
>&#34;ABSTRACT_SCHEMA&#34; in Bugzilla::DB::Schema</a>.</p>

<dl>
<dt><a name="bz_column_info"
><code  class="code">bz_column_info</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Get abstract column definition.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$table_-_The_name_of_the_table_the_column_is_in."
><code  class="code">$table</code> - The name of the table the column is in.</a></dt>

<dd>
<dt><a name="$column_-_The_name_of_the_column."
><code  class="code">$column</code> - The name of the column.</a></dt>
</dl>

<dt><a name="Returns"
><b>Returns</b></a></dt>

<dd>
<p>An abstract column definition for that column. If the table or column does not exist, we return <code  class="code">undef</code>.</p>
</dd>
</dl>

<dt><a name="bz_index_info"
><code  class="code">bz_index_info</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Get abstract index definition.</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$table_-_The_table_the_index_is_on."
><code  class="code">$table</code> - The table the index is on.</a></dt>

<dd>
<dt><a name="$index_-_The_name_of_the_index."
><code  class="code">$index</code> - The name of the index.</a></dt>
</dl>

<dt><a name="Returns"
><b>Returns</b></a></dt>

<dd>
<p>An abstract index definition for that index, always in hashref format. The hashref will always contain the <code  class="code">TYPE</code> element, but it will be an empty string if it&#39;s just a normal index.</p>

<p>If the index does not exist, we return <code  class="code">undef</code>.</p>
</dd>
</dl>
</dd>
</dl>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="Transaction_Methods"
>Transaction Methods</a></h2>

<p>These methods deal with the starting and stopping of transactions in the database.</p>

<dl>
<dt><a name="bz_in_transaction"
><code  class="code">bz_in_transaction</code></a></dt>

<dd>
<p>Returns <code  class="code">1</code> if we are currently in the middle of an uncommitted transaction, <code  class="code">0</code> otherwise.</p>

<dt><a name="bz_start_transaction"
><code  class="code">bz_start_transaction</code></a></dt>

<dd>
<p>Starts a transaction.</p>

<p>It is OK to call <code  class="code">bz_start_transaction</code> when you are already inside of a transaction. However, you must call <a href="#bz_commit_transaction" class="podlinkpod"
>&#34;bz_commit_transaction&#34;</a> as many times as you called <code  class="code">bz_start_transaction</code>, in order for your transaction to actually commit.</p>

<p>Bugzilla uses <code  class="code">REPEATABLE READ</code> transactions.</p>

<p>Returns nothing and takes no parameters.</p>

<dt><a name="bz_commit_transaction"
><code  class="code">bz_commit_transaction</code></a></dt>

<dd>
<p>Ends a transaction, commiting all changes. Returns nothing and takes no parameters.</p>

<dt><a name="bz_rollback_transaction"
><code  class="code">bz_rollback_transaction</code></a></dt>

<dd>
<p>Ends a transaction, rolling back all changes. Returns nothing and takes no parameters.</p>
</dd>
</dl>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="SUBCLASS_HELPERS"
>SUBCLASS HELPERS</a></h1>

<p>Methods in this class are intended to be used by subclasses to help them with their functions.</p>

<dl>
<dt><a name="db_new"
><code  class="code">db_new</code></a></dt>

<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>

<dd>
<p>Constructor</p>

<dt><a name="Params"
><b>Params</b></a></dt>

<dd>
<dl>
<dt><a name="$dsn_-_database_connection_string"
><code  class="code">$dsn</code> - database connection string</a></dt>

<dd>
<dt><a name="$user_-_username_used_to_log_in_to_the_database"
><code  class="code">$user</code> - username used to log in to the database</a></dt>

<dd>
<dt><a name="$pass_-_password_used_to_log_in_to_the_database"
><code  class="code">$pass</code> - password used to log in to the database</a></dt>

<dd>
<dt><a 
><code  class="code">\%override_attrs</code> - set of attributes for DB connection (optional). You only have to set attributes that you want to be different from the default attributes set inside of <code  class="code">db_new</code>.</a></dt>
</dl>

<dt><a name="Returns"
><b>Returns</b></a></dt>

<dd>
<p>A new instance of the DB class</p>

<dt><a name="Note"
><b>Note</b></a></dt>

<dd>
<p>The name of this constructor is not <code  class="code">new</code>, as that would make our check for implementation of <code  class="code">new</code> by derived class useless.</p>
</dd>
</dl>
</dd>
</dl>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="SEE_ALSO"
>SEE ALSO</a></h1>

<p><a href="../DBI.html" class="podlinkpod"
>DBI</a></p>

<p><a href="../Bugzilla/Constants.html#DB_MODULE" class="podlinkpod"
>&#34;DB_MODULE&#34; in Bugzilla::Constants</a></p>
<p class="backlinkbottom"><b><a name="___bottom" href="../index.html" title="All Documents">&lt;&lt;</a></b></p>

<!-- end doc -->

</body></html>
